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] . In troduct ion 

This manual describes the implementation details of the Atari 
PILOT language interpreter for the Atari Personal Computer 
System. The Atari PILOT language is described in a separate 
manual entitled 'ATARI PILOT EXTERNAL SPECIFICATION'. 

The PILOT interpreter resides in an 8K byte cartridge and uses 
all of the available RAM memory for its own static and dynamic 
memory requirements. Static memory requirements include: 

Interpreter working variables. 

Mode control and option flags. 

Numeric variable storage. 

Numeric expression stack. 

Use stack. 

Accept, text expression and command line buffers. 

Dynamic memory requirements include: 

Program statement storage. 

String variable storage. 

Graphics/ text screen area. 

The interpreter utilizes the Screen Editor as a source for 
command lines, which may be immediate commands, deferred PILOT 
statements or line deletions; thus, full line editing is 
provided before the interpreter sees the input line. 

The interpreter utilizes PILOT source statements for all 
operations; the statements are never tokenized, compiled or 
transformed in any way, except that line numb- cs are converted 
to integer form for internal program storage. 
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2. Interpreter operation 

The interpreter is at all times reading PILOT statements, but 
depending upon the operating mode different actions are taken. 
The primary operating modes and their behaviors are: 

Immediate mode -- PILOT statements are read from the Screen 
Editor and result in either immediate execution, a storage to 
the program storage area or a statement deletion. 

Run mode -- PILOT statements are read from the program storage 
area and executed. 



Auto-number input mode -- PILOT statements are read from the 
Screen Editor, a line number is appended and the resultant 
statement is stored to the program storage area. 



Load mode -- PILOT statements are read from a user specified 
device, otherwise this mode is identical to immediate mode. 
Normally PILOT loads from a file containing only numbered 
statements which are then stored to the program storage area; 
however, un-numbered PILOT statements contained within 
loading file will be executed as encountered. 



a 



The modes will be discussed in more detail in the paragraphs 
that follow. 



2.1 Command/statement scanning 

PILOT statements are scanned on a strict left to right basis 
using a context independent recursive lexical analyzer which 
identifies and evaluates all data elements and operators. PILOT 
statements undergo a double scan process: first a syntax scan 
which rejects all syntact ical ly incorrect statements and then an 
execute scan. Even immediate mode commands are double scanned to 
minimize the occurrence of unwanted side effects from partially 
executed invalid commands. PILOT statements in the program 
storage area are syntax checked at the time of entry (immediate 
mode, load mode or Auto-number input mode) and then are not 
syntax checked again during run mode, in order to maximize the 
execution speed. 

The same routines are used for both the syntax scan and the 
execute scan with a flag indicating which type of scan is to be 
per formed . 



2.2 Immediate mode 

Immediate mode is the default operating mode; when in this mode 
the interpreter reads PILOT commands/statements from the Screen 
Editor and operates upon them. Input lines consists of an 
optional line number and an optional PILOT statement with the 
following rules governing the interpreters actions: 

line $ PILOT resultant action 

statement 

YES YES Store line in program storage area 
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YES 


NO 


MO 


YES 


MG 


NO 



Delete line from program storage. 
Execute statement immediately. 
Mo-operation (ignore) . 



2.3 Run mode 

While in run mode, the interpreter executes previously stored 
PILOT statements from the program storage area. Run mode is 
entered by the immediate mode execution of a Run, Jump, Cse or 
End command. Run mode is terminated by a run-time error, the 
end of program execution, an operator BREAK or system RESET. 

2.4 Auto-number input mode 

While in auto-number input mode, the interpreter accepts un- 
numbered PILOT statements from the Screen Editor, appends an 
internally generated line number to each statement and stores 
the resultant statement to the program storage area. Syntax 
errors are reported and the offending statement is not stored. 

Auto-number input mode is entered by the immediate mode 
execution of an Auto command and is terminated by the operator 
entry of an empty line. 



2.5 Load mode 

Load mode is identical to immediate mode, with the exception 
that statements are read from a specified device/file rather 
than from the Screen Editor. Load mode is entered by the 
execution of a Load command and is terminated by an I/O error or 
an end-of-file condition from tne device/file being read. 



2.6 Graphics mode 

Graphics mode is a screen mode, rather than an operating mode as 
discussed in the preceding paragraphs. The screen is usually in 
one of two modes, text mode or graphics mode. The default mode 
is text mode in which the screen is organized as 24 lines of 40 
characters each. The user may select graphics mode by the 
execution of the Graphics command, in which case the screen is 
reorganized to a graphics screen with a 4 line text window at 
the bottom. 

The current mode and the transitions between modes are carefully 
controlled and monitored by the interpreter because: 

The highest available RAM location changes when going into 
and out of graphics mode, thus requiring a movement of the 
string variable list. 

Different C.S. interfaces and database variables are 
utilized for screen I/O in the two modes. 
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3. Special considerations 

The paragraphs that follow discuss some of the special 
considerations that were made during the design and 
implementation of the Atari PILOT interpreter. 



3.1 Error reporting 

In order to aid the user in the correction of syntax errors, the 
interpreter highlights a character, in tne offending statement, 
that is the source of the error or is immediately to the right 
of a field that is incorrectly specified. The fact that the 
highlighting is usually to the right of the error is a 
consequence of the fact that tne lexical analyzer never 
backtracks, that data type errors are detected after lexical 
scanning and that syntactical ambiguities may lead to the 
postponement of error detection. 



3.2 BREAK key monitoring 

The BREAK key is supposed to provide a graceful termination of 
any on-going process; accordingly the pilot interpreter monitors 
the BREAK key at the following points: 

Between the scanning of each statement (all modes). 
Periodically during the execution of the Pause command. 
Periodically during the execution of the Tsync command. 
Between the execution of each Graphics sub-command. 

When an operator BREAK is detected, the interpreter stops the 
then current activity and returns to immediate mode execution. 



3.2 Trace mode 

Trace mode is a special mode which may be utilized in 
conjunction with run mode to aid in the debugging of PILOT 
programs. While in trace mode, the interpreter will write to 
the text screen (or window) the PILOT statement about to be 
executed; this is done regardless of whether or not the 
statement condition field evaluates to true or false. 



3.3 Run-time error minimization 



Some steps have been taken to minimize the possibilites for 
producing run-time errors in PILOT programs; among the items 
accounted for are: 

All statements are syntax checked before being stored to the 
program storage area. 

Accept buffer and text expression buffer results are 
truncated on overflow, with no error reported. 

The accept buffer and command line input buffer are larger 
tnan the largest line which may be entered from the Screen 
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Editor. 

The graphics screen cursor control includes in-bounds/out- 
bounds tests and line clipping to eliminate "cursor out of 
bounds" errors from the Display Handler. 

No explicit OPEN command is provided, the device/filename 
and the data direction being provided by the READ and WRITE 
commands themselves. 

The string variable list is moved when entering graphics 
mode so that "insufficient memory" error will not occur 
except when there is really not enough memory. 

The Use stack is cleared on immediate mode execution of Run, 
New, program statement insertion, program statement deletion 
and run mode execution of Load, so that the Use stack is 
guaranteed always to be empty or to contain valid return 
addresses . 

String variable operations are allowed on null strings and 
undefined strings and no explicit declaration of string 
length is required (or allowed for that matter). 
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4. Internal data structures 

This section details the internal data structures used by the 
PILOT interpreter. A memory map showing the gross use of RAM is 
provided below: 



O.S. 



P I LOT 



stack 



n c 

'j • u • 

data 

base 



PILOT 
static 
var iables 

system 

booted 

software 

accept 

buffer 



program 

storage 



free 

region 



string 

storage 



Screen 
Ed i tor 
c isplay 
data 



0000-007F 



£ 08Q-00FF 



010O-01FF 



020B-04FF 



0500-36FF 



£700-???? (need not be present) 



(one memory page) 



????-end of PAM 



PILOT utilizes the entire second half of memory page zero (Q08C- 
00FF) for variables, pointers and tables, and in addition, 
utilizes pages 5 and 6 (85C0-Q5FF) for the same. Memory page 1 

contains the 6502 hardware stack and is completely reserved for 
that purpose. 



PILOT starts the program storage area at the bottom of the free 
memory region at power-up time. If no disk or cassette software 
was booted, that address will be 07££, otherwise the address 
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will be at the end of the booted software. PILOT starts the 
string storage area at the top of memory just below the display 
list/data region reserved by the Screen Editor. 



V rv x l \ x 



r x uu x 



iniij i \i.\ n i_j 



/ 



4.1 Strings 

String variables are dynamically assigned from the high address 
region of the free memory space downward. The variables are 
stored in a structure called the string list which is ordered by 
the collation seouence of the variable names contained therein. 
String names and their values are stored using standard ATASCII 
encoding, one character per 8-bit byte. 

4.1.1 String storage 

String variables (strings) are stored in memory using sequential 
storage, with two pointers demarking the beginning and end of 
the storage area. Pointer S2H [0034] marks the end of the list 
and does not change (except when entering or exiting graphics 
mode); pointer S2L [0032] marks the start of the list and 
changes every time an item is inserted or deleted. 



+ 

I 

+ 




+ 

I 

+ 



+ 

S2H *- + 
+ 



+ 

>1 

+ 

I 

+ 

I 

I 

+ 

I 

+ 

> 



+ 

I 

+ 

I 

+ 



+ 

last item | 
+ 

(1st byte after 



1st item 



2nd item 



low memory address. 



high memory address, 
last item) 



When the string list is empty, S2L and S2H both point to the 
first unusable byte at the end of memory. The value of S2H is 
established from C.S. variable MEMTOP [02E5] at power-up time 
and is readjusted whenever there is a change in the screen mode 
due to a Graphics command execution. 
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Each item in the string list has the format shewn below: 



7 0 

+ + 

I item size I The item size is also used as 

+- -+ a relative pointer to the next 

I I item in the list. 

•+* — — — — — — — — h 

I name size I ! to 254. 

+ + 

I name value I 

I I 

= 1 to 254 

I bytes of I 

I ATASCII I 

+ + 

I data size ! 6 to 254. 

+ + 

I data value I 

I I 

= 0 to 254 

I bytes of I 

I ATASCII I 

-j — — — — — — — — — h 



The first item in the list 
in the collation sequence, 
ordered accordingly. 



is the variable with the name lowest 
with the rest of the list being 



4.1.2 String pointers 

When scanning and manipulating strings the interpreter utilizes 
^-byte pointers which contain a 16-bit base address plus 8-bit 
unsigned offsets to the beginning and end of the substring being 
dealt with. 
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7 0 

+ + 

I base I 

+ - - + 

I pointer I 

+ + 

I start offset I 

+ + 

lend offset (+1)1 

+ + 



The pointer to a null substring will have the start offset equal 
to the end offset. 
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4.1.3 String variable name and value pointers 

The lexical analyzer returns, as part of its calling sequence, a 
pointer to the name and a pointer to the value of each named 




string variable it encounters. The name pointer is returned in 
4-byte pointer variable NP [Q03E] and the value pointer is 
returned in 4-byte pointer variable DP f 0 0C 2 ] ; see section 4.1.2 
for the format of the 4-byte pointer variables. 



4.1.4 String name temporary 

In order to solve a problem arising from the use of string 
indirection in the target for a Compute or Accept command (e.g. 

' C : $$ABC=$D£F * ) , all target string names are moved to a 
dynamically allocated memory region prior to evaluating the text 
expression to the right of the ' = This region is 257 bytes in 
extent and is allocated upward from the top of the program list, 
and deallocated at the end of the command execution. If 
unsufficient memory is available for the allocation, the 
interpreter will produce a run-time error. 
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4 . 2 Numbers 

All PILOT language numeric data is stored internally in 16-bit 
two's complement integer form, with the least significant byte 
(Isb) being at the lower address. Numeric overflow may occur 
a result of some numeric operations and is not considered an 
error by the interpreter. 



4.2.1 Numeric variables 

The PILOT numeric variables ' #A ' through ' #Z 1 are stored 
sequent i ally in a statically assigned table which starts at 
location 0 5 IB. 



H h 

I value | 

+ + 

I #3 value | 

+ + 

I #C value | 



+ 



+ 



address = fi51B. 



+ 

I f Z value 
+ 



+ 

I 

+ 
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as 
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4,2.2 Numeric expression stack 



Numeric expressions are evaluated using an expression stack 
which is statically assigned and has room for the partial 
results to support two levels of nested (non-r edundant) 
parentheses. The stack is shown below prior to final evaluation 
of the expression #A + (#C / 4); notice that the stack contains 
the expression operands and operators in the same infix form as 
seen in the statement of the expression. The stack entry for 
each operator is the ROM address of the arithmetic routine which 
is to perform the diadic operation; when the operation has been 
completed, the three words at the then current top of stack will 
have been replaced with the numeric result of the operation. 



+ + 

I #A value | bottom of stack addr = G£93. 

H 1- 

I + oper. | 

+ + 

I #C value | 

+ 4 

I / oper. | 

+ + 

I 4 | 

4 + 4- + 

I ESTKP * + > t current I 

4 4- = top of = 

I stack +2 | 

4 4 

I I 

4 + 



The expression stack pointer ESTKP [0091] is a single byte 
quantity which contains an index value to the word beyond the 
current top of stack (next available free word). For the case 
of an empty stack ESTKP contains 0 and is then incremented by 2 
for every item added to the stack and decremented by 2 for every 
item deleted from the stack. 



4.2.3 Numeric result value and address. 

The lexical analyzer returns, as part of its calling sequence, 
the integer value and the address of each numeric variable or 
pointer variable it encounters. 3r va ^ ue returned 

in variable NUMBER [00B8] and the s returned in variable 

POINT [0036]. For special variables (%x) and numeric constants 
the integer value is returned in NUMBER, and POINT is not 
altered. 
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4.3 Program storage 

Deferred program statements are stored in memory using 
sequential storage, with two pointers demarking the beginning 
and end of the storage area. Pointer S1L [ 0 £AE ] marks the start 
of the list and does not change; pointer S1H [08B01 marks the 
end of the list and changes every time an item is inserted or 
deleted . 



+ + 

I S ] L *-+ 
+ + 

4 - + 

| S 1 H *- + 
+ + 



+ 

>1 

+ 



4 - 



t 

+ 



+ 



1st 


i tem 


2nd 


i tem 




last 


i tem 



4 - 

I 

4 - 



+ 

I 



+ 

I 

+ 



low memory address. 



I high memory address 



> (1st byte after last item) 



When the program list is empty, S1L and S1H both point to the 
first usable byte at the beginning of the free memory region. 
The value of S1L is established from O.S. variable MEMLO [02E71 
at power-up time and is not altered thereafter. 

Each item in the program list has the format shown below: 



7 


0 






+ - 


+ 






i 


item size | 


The item size is a 


Iso used as 


+- 

i 


-+ 

i 


a relative pointer 
item in the list. 


to the next 


+ - 


+ 






i 


2 1 






+ - 


+ 






i 


line numbe r | 


Contains the binary line 


+ - 
i 


-+ 

i 


number in msb/lsb 


o r d e r . 


! 

+ - 






i 


s ta temen t s i ze | 


1 to 254. 




+ - 








i 


statement I 






i 


i 


Contains a single 


P I LOT 


i 


1 to 254 
bytes of 1 


source statement . 




i 


ATA5CII. I 






4- — 


+ 







The first item in the list is the 
number, with the rest of the list 



statement with the lowest line 
being ordered accordingly. 



The fact that a program list entry is a special case of 



s 1 1 i no 






list entry is purely intentional. 



4.4 Use stack 

The return addresses for Use commands are retained in a stack 
which is statically assigned and has room for eight entries. 
Each stack entry is the memory address of the statement after 
the one containing the executed Use command. 



H — — — — — -f- 

I return | bottom of stack addr = O503. 
+ - addr - + 

I #1 I 
+ + 

I return | 

+- addr - + 

I # 2 | 

+ + 

+ + I current | 

I IJSTKP * + > +- top of - + 

+ + I stack + 2 | 

+ + 



+ - 
I 

+- 

I 

+- 



+ 

return | 

addr -+ 

#8 I 

+ 



The Use stack pointer IJSTKP [0090] is a single byte quantity 
which contains an index value to the word beyond the current 
top of stack (next available free word). For the case of an 
empty scack IJSTKF < antains 0 and is then incremented by 2 for 
every item added to the stack (Use command) and decremented by 



for 



every item deleted from the stack (End command) 
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4.5 Buffers 



The PILOT interpreter contains several text buffers, which are 
each defined and delimited by a corresponding 4-byte pointer. 
Each of tne buffers is described in the paragraphs that follow. 



4.5.1 Command line input pointer /buff er 



The command line input pointer INLN [0080] is a 4-byte pointer, 
as described in section 4.1.2, which points to and delimits the 
PILOT command/statement to be executed. When in immediate mode, 
INLN points to the buffer COMBIJF [0676] which is the target for 
a logical line of text from the Screen Editor. The example 
below shows the state of the command line input pointer/buffer 
immediately after the input of 'RUN* from the screen. 



INLN = 0 08 C 



COMBIJF = B676-B6F0 



+ — — + 

I base * - + 



+ - 



- + 



address 



I s tar tx= 0 I 

4 4. 

| endx = 4 | 

4 4* 



<EOL> 



When PILOT is in run mode, the INLN pointer points to program 
statements in the program storage area (instead of COMBUF). In 
that case tne base address points to the beginning of the 
statement allocation and the start index contains a value of 6 
which offsets the overhead bytes. See section 4.3 for the 
format of the program statement storage. 
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4.5.2 Accept pointer/buffer 

The accept buffer pointer ACLN [0088] is a 4-byce oointer, 
as described in section 4.1. 2 , which points to and delimits the 
current accept buffer contents. ACLN always points to the 
dynamically assigned accept buffer which resides in the 256 byt. 
page at the beginning of the free memory region. The buffer is 
allocated at power-up time and starts at the then current 
address contained in O.S. variable MEMLO [02E7]. The example 
below shows the state of the accept buffer pointer/buffer 
immediately after the execution of the PILOT statement 
1 A : =HELLO ' 



ACLN = 00S8 address assigned at power-up 

+ + 

I base *- + 

+ - - + 

I address I 

+ f 

|startx= 0 I 

4. 4- 

| endx = 7 | 

4 - + 



+ 4 - 

> | <blank> I 

+ 4. 

I H | 

4 - + 

I E I 

4- + 

I L I 

4. + 

I L I 

+ + 

I o | 

4- 4- 

I < b 1 a n k > I 

+ 4 - 
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4.5.3 Text expression evaluation pointer/buf f er 

The text expression buffer pointer TELN [ 0 C5 8C ] is a 4-byte 
pointer, as described in section 4.1.2, which points to and 
delimits the result of the evaluation of a PILOT text 
expression. TELN always points to the buffer TEX3UF [0577]. 

The example below shows the state of the text expression 
evaluation pointer/buf fer immediately after the execution of the 
PILOT statements ' C : $NAME=JOE 1 and *T:HI, $NAME\ ’ . 



TELN = 0 08C TEXBUF = 0577-0675 




> 



4 

I 

4 

I 

+ 

I 

4 

I 

4 

I 

+ 

I 

4- 

I 

4 



H 



I 



< b 1 a n k > 



J 



0 



E 



+ 

I 

4 

! 

4 

I 

4 

I 

4 

I 

4 

I 

4 

I 

4 



+ 4 

I I 

4 4 



Although TEXBUF could in theory be dynamically assigned, there 
is code within the interpreter which accesses the buffer by name 
rather than using the pointer TELN, thus making dynamic 
assignment impossible (without coding changes to the 
interpreter) . 



L. 
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4.6 Graphics parameters 

The internal graphics routines use several different types of 
variables to perform the screen graphics computations, most of 
which relate to either line clipping or direction calculations. 



4.6.1 X & Y coordinates 



To minimize the effects of accumulating errors when performing 
relative cursor movement (DRAW, GC or FILL), where the cursor 
positions are not general integral, the graphics coordinates are 
maintained in memory in a. 3-byte format as shown below: 







— + 




1 


1 sb 


i 


byte 0 


+- 

I 


msb 


-+ 

i 


i 


+ - 




- + 





I fraction I 2 

1 — — — h 



Each coordinate contains two bytes of integer and one byte of 
fraction, all in two’s complement representa t ion . When data is 
either plotted to the screen, read from the screen or the 
coordinate values accessed using '^X* and 1 %Y ' , the most 
significant bit of each fraction is used to round the integer 
values of the coordinates (working values only, not the 
reference value). 

The coordinate reference values are contained in variables GX 
[ 0 0EC ] and GY [0GEF]; other working variables also utilize this 
format as shown below: 



Ncme 


Funct ion 










GX 


Current cursor 


x-coord ina te . 






GY 


Current cursor 


y-coor d i na te . 






GXNEW 


Cursor target 


pos i t i on 


x-coord i n 


u L • 


GYNEW 


Cursor target 


pos i t i on 


v-coord i nate . 


GX1 


Line clipping 


line end 


point 


i , 


x-coor a 


GY 1 


Line clipping 


line end 


point 


i , 


y - c o o r d 


GX2 


Li ne cl ipping 


line end 


po i nt 


2, 


x-coord 


GY2 


Line clipping 


line end 


po i n t 


2, 


y-coord 



4.6.2 Theta angle 

The graphics theta angle is maintained internally in variable 
THETA [00F2] as an integer value that ranges from £> to 359 . The 
graphics variable 1 %A * returns this value directly. 
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4.6.3 Pen color 

The currently selected pen color is retained in single byte 
variable PEN [3553] which may have the following values: 

8 = ERASE. 

1 = RED. 

2 = YELLOW. 

3 = 3 LUE . 

4 = UP. 



4.6.4 Computations variables 



The following variables are used during the computation of line 
end points by the clipping algorithm: 



DELX [ 8 GC A ] 
DELY [ 0 GCC ] 



Integer delta x (line slope). 
Integer delta y (line slope). 



GACC [ 0 EC E ] 
GTEMP [ 8 GD 2 ] 
GTEMP2 f 0 3D6 ] 



4 byte integer accumulator. 
4 byte integer temporary. 

4 byte integer temporary. 
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4 . 7 Sounds 



The sound parameters for the Sound command are retained in a 
statically allocated table as shown below: 



+ 



+ 



+ 



+ 



+ 



entry #4 



+ 



entry 4 3 



+ 



entry #2 



+ 



entry #1 



+ 



low memory address = 0555. 



Each table entry is a 2-byte quantity with one of the two 
formats shown below: 



7 0 

+-+-+ -+-+-+ -+-+-+ 
I memory lo I 
+-+ - + 

I G | address hi | 



Byte 0 
1 



o r 



7 0 

H — + — h — H — 4- — f- — K — I V 

I (unused) I 

h — i — i — ; — i — i — i — i — h 

I 1 | x x | constant I 



Byte 0 
l 



An entry of all zeros is used to flag the current end of the 
table unless the table is full. The table is scanned from the 
high memory address to the low memory address until the logical 
or physical end of table is reached. 

The data value at the address specified by the table entry, or 
the stored constant, is truncated to a 5-bit quantity which is 
then used as a table index to obtain one of the 32 values shown 
in the table below. The value obtained from the table is sent 
to one of the hardware audio registers to generate the desired 
tone . 
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^ C i -A. A . A \ .i 


X AJ X A L» 1 


wi'ir; u v; r XI. 


X V. C" X X V/ - 


l J. — 1 > W V 


Numer i c 


A u d i o 


No t e 


Fr eq . 


Fr ea . 


Error 


value 


register 




(desired) 


(actual) 


(%) 


0 


0 


rest 


0. 0 


31960.50 


_ 


1 


24 3 


C 


1 30.81 


130.99 


+ 0.14 


o 

z 


2 30 


C# 


1 38.59 


1 38.36 


-0.17 




217 


D 


146.83 


146.61 


-3.1 5 


4 


204 


D# 


155.56 


1 55. 90 


+ 0.22 


5 


193 


E 


164.81 


164.74 


-0.04 


6 


182 


F 


174.61 


174.65 


+ 0.62 


7 


172 


F* 


185.00 


184.74 


-0.14 


£ 


162 


G 


196.00 


196.08 


+ 0.04 


9 


153 


G# 


207.65 


207.54 


- 0 . 0 5 


1 0 


144 


A 


220.00 


220. 42 


+ 0.19 


11 


1 36 


A# 


233.08 


233. 29 


+ 0 . 0 9 


12 


1 28 


B 


246.94 


247.76 


+ 0.33 


1 3 


121 


C 


261.63 


261.97 


+ 0.13 


1 4 


1 1 4 


c# 


277. IS 


277.92 


+ 0.27 


15 


108 


D 


293.66 


293.22 


-0.15 


16 


182 


D# 


311.13 


3 1 E . 3 0 


-6.27 


17 


96 


E 


329.63 


329. 49 


-0.04 


1 8 


91 


F 


349. 23 


347.40 


-0.52 


1 9 


85 


F# 


369. 99 


1 — i 

• 


+ 0.44 


20 


81 


G 


392.P0 


389.76 


-0.57 


21 


76 


G# 


415.30 


4 1 5. P7 


-0.06 


22 


72 


A 


4^0.00 


437.82 


-0.53 


23 


68 


A r 


466.16 


46 3. 20 


- 0 . 6 3 


24 


64 


B 


493.88 


491.70 


-0.44 


25 


60 


C 


523.25 


523.94 


+ 0.13 


r- 

Z 0 


57 


c# 


554.37 


551. f ! 4 


-0.60 


27 


5 3 


D 


587. 33 


591.86 


+ 0.77 


28 


50 


D# 


622.25 


626.68 


+ 0.71 


29 


47 


E 


659.26 


655.84 


+ 1.00 


30 


45 


F 


698.46 


694.79 


-0.53 


31 


42 


F# 


739.99 


743.27 


+ 0.4^ 



The formula for converting audio register values to frequency 
i s : 

frequency = 63921 / (2 * (audio register value 4-1)) 



r i 
L A 



r i 

L A 




* 



4.8 Command/r eserved word tables 

All command name, numeric and relation operator, and reserved 
word recognition is performed using a single segmented table 
contained in the cartridge ROM (CTAB) . The format for that 
table is shown below: 



+ 



+ 



PILOT 
command s 



+ 



4* 



numer i c/ 
relation 
operators 

Mm 



4 



4 



graphics 
s ub-comm 



4 



+ 



pen 

colors 



4 



4 



'ON* /•OFF* 



4 



+ 



Each segment in the table contains 
a segment terminator byte of zero, 
below : 



one or more name entries olus 

w 

A single name entry is shown 



7 0 



+ - 


+ - 


-4- 


- 4- 


4-4 


— 


4-- 


4 — 


+ 


1 0 


I 














l 


+ - 


+ 












— 


f 


1 fl 


1 




C X 


act 








1 


— 






n a 


me 


• 

i 


n 
l l 




= 


1 0 


1 




A ~ 


C 1 1 








i 


+ - 


+ 












— 


+ 


1 0 


1 














l 


+ - 


+ - 


-4- 


-4 — 


4—4 


— 


H — 


4 — 


+ 


1 1 


1 




V 


alu 


e 






l 


+ - 


+ - 


-4-- 


- 4 — 


4-4 


— 


4- 


4- 


4 



In some cases the 7-bit value associated with a name is 
sufficient, for example the graphics pen color definitions. In 
other cases the 7-bit value is used as an index to a table of .16 
bit values (CDTA3) . 
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5. Procedure modules 

This section provides module descriptions for the major 
subsystems that were used to implement the Atari PILOT 
interpreter. 



5.1 Memory management package 

This package contains the routines listed below, all having 
functions relating to the management of memory resources: 



M ALLOC 
MDEALL 
MO VI A - 
MOVDA - 



Memory allocate. 

Memory deallocate. 

Move memory block using increasing 
Move memory block using decreasing 



addresses . 
addresses . 



This memory management scheme utilizes two separate allocation 
regions; one region starting in low address memory and working 
upward, and the other region starting in high address memory 
and working downward. In PILOT, one region is used for program 
storage and the other region for string variable storage. The 
regions are initially defined by four pointers: 



S1L = 
SIH = 
S2L = 
S2H = 



Po inter 
Pointer 
Po i nter 
Pointer 



to start (bottom) of region 
to end (top) of region 1. 
to end (bottom) of region 2 
to start (top) of region 2. 



] (lower region) 
(upper region) . 



S1L and S2H define the extent of managed memory and are not 
altered by the management routines. SIH and S2L are initially 
equal to S1L and S2H (respectively) indicating null allocations, 
and thereafter always point to the next available unused memory 
location. Allocation of memory is accomplished by creating a 
"hole" in the desired region (by moving memory if necessary) ; 
and deallocation of memory is accomplished by eliminating a 
"hole" in the region. An allocated block of memory always 
contains its own size as the first (lowest address) two bytes of 
the block; this is the only memory overhead associated with 
management. Note, however, that the block size also forms a 
relative pointer to the next allocation block which can be 
useful to the application if the blocks within a region form a 
sequent ial list. 

The user always specifies the address at which allocation is to 
start; this address may be inside the region ("between" already 
allocated blocks) or may be the next available address just 
outside the region. The user specifies the address of the block 
to deallocate also, the size is assumed to still be in the first 
two bytes of the block. 

The section that follows summarizes the calling sequences of the 
current routines: 

M ALLOC -- Memory allocate routine 

Calling sequence : 



VMEMA' contains the address at which the allocation is to occur 
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This address is either the next available address outside 
the region (content of 51H or S2L) or the address of an 
already allocated block within the region. 

'MEMB* contains the number of bytes to allocate, including the 
two overhead bytes. 

J5R MALLOC 

BNE not enough memory to satisfy allocation 

'MEMA* contains the lowest address in the allocated block. 

The first (lowest) two bytes of the allocated block contain the 

number of bytes in the block. 



MDEALL -- Memory deallocate routine 
Calling sequence: 

1 MEMA * contains the address of the block to deallocate. The first 

(lowest) two bytes of the block must contain the block size. 

JSR MDEALL 

'MEMA 1 contains the address of the block following (higher address) 
the deallocated block after the deallocate. 



MCVOA and MGVIA are used by MALLOC and MDEALL; they are general 
purpose block move utilities and their calling sequences may be 
obtained from the source file. 




A 



-*■ fc * *• *— * J ' V 1 



J. U V JL L X w I 1 i 



X v_> L ^ 



JL J. L>» ^ V — U U ) 



5.2 String handling package 

This package contains the routines listed below, all having 
functions relating to the handling of named strings of variable 
1 eng th . 



S FIND -- Find named string in list. 

SDELET -- Delete named string from list (if it exists). 
SINSRT -- Insert named string into list (by name order). 
SMATCH -- Find substring in string, if present. 

5C0MP -- Compare two strings for collation. 



This package utilizes the memory management package described in 
section 5.1 and deals with two separate lists of named strings, 

where one list is the program list and the other is the string 
variable list. 



In order to understand the calling sequences, a few definitions 
must be given first: 

Text data -- any contiguous grouping of one or more bytes which 
are to be treated as a unit. The word 'JACK', when stored in 
memory as shown below, is an example of text data. 

+ + + + + 

I'J • I'A ' I'C ' I'K ' | 

+ + + + + 



String -- text data to which a string length byte has been 
appended, as shown below. 

+ + + + + + 

I 4 ! ’ J ' ! ’ A ’ | ' C • I • K ’ I 

-j — — — - 4 - -4 + -| -f. 



Text pointer — a four byte element consisting of a base memory 
address and two indices (a starting and an ending index). The 
text pointer explicitly delimits a (possibly null) group of 
bytes starting with the byte at address EASE ADDRESS + START 
INDEX and ending with the byte at address BASE ADDRESS + END 
INDEX - 1 . By convention, if the start index equals the end 
index, the text data is considered to be null. See also section 
4.1.2. 



Named string -- a string which can be referenced by a symbolic 
name consisting of text data; a named string is often known as a 
string variable. The name and data portions may each be up to 
254 bytes in length. See section 4.1.1 for the storage format 
for named strings. 



Parameter area -- a portion of page zero memory which contains 
text pointers which have assigned meanings for each of the 
string operations provided by this package. These parameters 
are initially setup by the user and provide the parameter 
passing mechanism for all operations. 
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NP (name pointer) -- when used, this delimits a 
string name. 




DP 



(data pointer) -- this delimits string data; often 
associated with the named string specified by NP. 



MP (pattern match pointer) -- when used, this 

delimits comparison or pattern matching data to be 
used in conjunction with DP. 

LP (list pointer) -- points to the string list to be 
accessed . 



The section that follows summarizes the calling sequences of the 
routines: 



S FIND -- Find named string in list. 

Function: SFIND scans a list of named strings, attempting to find 
the name delimited by the NP text pointer. If the named string 
is found, DP will point to the string data. 

Calling sequence: 

LP = address of start of list of named strings. 

NP = text pointer delimiting a string name. 



J3R 

ENE 




SFIND 

name null or named string not found 

text pointer to string data portion, if found. Base 
address points to string byte count (n) , start index 
= 1 and end index = n+1 (assuming non-null data, else 
both indices = 1 ) . 



SDELET -- Delete named string, if found. 

Function: Finds the named string, if it exists, removes the named 
string from the list and deallocates the memory utilized by 
that string. 



Calling sequence: 



LP = address o 



■f- c- 

X. CD 



tart of string list to access. 



NP = text pointer delimiting a string name. 



J3R 

BNE 



SDELET 

name null or named string not found 




SINSRT -- Insert named string to list. 

Function: Deletes a prior occurrence of the named string, 
and then inserts the new named string into the list. The 
string is placed in the list so that the names are in 
standard collation order. 



if found , 



Calling sequence : 
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LP = address of start of string list to access. 
NP = text pointer to string name. 

DP = text pointer to string data. 

JSR SIN3PT 

ONE no room in memory for insertion 



5 MATCH -- Find substring in string if present. 

Function: examine string for first occurrence of substring. 
Calling sequence : 

DP = text pointer to source text data. 

MP - text pointer to match text data. 

JSR 3MATCH 

RNE match text not in source text 

SP = text pointer to first occurrence of match data in source. 



SCOMP -- Compare two string for collation order. 



Function: compares two strings to determine their collation order. 
Calling sequence: 



DP 

MP 



text pointer to 
text pointer to 



text data, 
text data. 



JSR 

BEC 

ECS 

BCC 



SCOMP 

DP text data 
DP text data 
DP text data 



= MP text data 
>= MP text data 
< MP text data 



Note : The comparison is based upon the numerical encoding of 
the characters involved; moreover , when one text data is a sub- 
set of the other text-data, the shorter one is considered to be 
lower (<) in the collation sequence. 



Routines I FIND, 
a id SNXTI are lo 
described above. 



I COMP , IMATCH, SEND, ILENG, PSETtJP, PMCVE 
wer level routines used to implement the 
Their calling sequences may be found in 



, 5 MQV I 

O n o q 

vy 4 i w ^ 

the 



source liscing. 
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5.2 Integer arithmetic package 

Double Precision Integer (Signed) Arithmetic Package (DXXXIY) 

This package contains the routines listed below, all having 
functions relating to two-byte signed integer arithmetic 
(except as noted) : 



Funct ion 



Routine(s) 



Addition 


DADDI , 


DADDS , 


Subtraction 


DSUBI , 


DSU3A 


Multiplication 


DMULI 




Di v i s i on/modul us 


DD I VI , 


DM CD I 


Compar i son 


DSCMI , 


DCMPI , 


Negation 


CNEGI 




Relational tests 


DEQTI , 


DNETI , 


Number to ASCII 


DECASC 




ASCII to number 


ASCDEC 




Move number 


DMO VI , 


DLOADA 


These routines have 


a common 


call i ng 


All data is assumed 


to be two 


bytes 



DLTTI, DLET1 



followed by high byte), and all data is referenced by its 
position relative to the symbol 'DTA3*. The sample program 
that follows will hopefully make this clear. 



; DATA REGION 

f 

* = $B 0 

DTAB=* 

/ 

V A *=*+2 

VB *=*+2 

VC *=*+2 

• 

; PROGRAM REGION 

/ 

*=$B033 



; ORIGIN OF DATA REGION. 

; START OF DOUBLE PRECISION DATA. 

; DECLARE ' VA ' . 

; DECLARE ' V3 ' . 

; DECLARE 'VC'. 



; ORIGIN OF PROGRAM REGION. 



; COMPUTE VC = (VC + VM * (V3 ** 2) - 2. 



LDX * VC-DTAB ; VC = (VC + V a ) ... 

LDY # VA-DTAB 

JSR DADDI 



LDY # VB - D T A B ; ... * (VB ** 2) ... 

JSR DMTJLI 

JSR DMIJLI 



LDA $-2 

JSR DADDS 



The double orocision subroutines 
and Y registers; and since the X 
destination of the result, great 



do not, in general, alter the X 
register always specifies the 
savings in code can be achieved 
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when computing expressions with several terms by not including 
the redundant LDXs and LDYs . 

The section that follows summarizes the calling sequences of the 
resident routines. 

Name Function 



DADD I 

DADDS 

DADDA 

DStJBI 

DSUBA 

DMULI 

DDIVI 

DMCDI 

DNEGI 

DMC-VI 

DLOADA 

DSTORA 



DTAB (X) 
DTAB(X) 
'ACC 1 = 
DTAB (X) 

* ACC 1 = 
DTAB (X) 
DTAB { X ) 
DTAB (X) 
DTAB (X) 
DTAB (X) 
'ACC* = 
DTAB (X) 



= DTAB ( X ) + DTAB(Y) 

= DTAB(X) +/- A 
'ACC* + DTAB(Y) 

= DTAB ( X ) - DTAB(Y) 

* ACC 1 - DTAB(Y) 

= DTAB ( X ) * DTAB ( Y) 

= DTAB ( X ) / DTAB(Y) 

= ABS (DTAB (X ) ) MOD ABS ( DTAB ( Y ) ) 
= - DTAB ( X ) 

= DTAB(Y) 

DTAB (Y) 

= 'ACC' 



DSCMI 
DCMPI 
DCWCI 
DC MPA 



cc 


= DTAB ( X ) 


: DTAB(Y) 


(SIGNED) 


cc 


= DTAB ( X ) 


: DTAB(Y) 


(UNSIGNED) 


cc 


= DTAB ( X ) 


: A , Y 


(UNSIGNED) 


cc 


= 'ACC' : 


DTAB (Y) 


(UNSIGNED) 



DECTI 


DTAB (X) 


-- 


1 


IF 


DNETI 


DTAB (X) 


— 


1 


IE 


DGTTI 


DTAB (X) 




] 


IE 


DGETI 


DTAB (X) 


— 


] 


IE 


DLTTT 


DTAB ( X ) 




1 


IE 


DLETI 


DTAB (X) 


= 


] 


IE 



DTAB ( X ) = DTAB(Y), ELSE 0. 
DTAB ( X ) <> DTAB(Y), ELSE 0. 

DTAB ( X ) > DTAB ( Y ) , ELSE f. 

DTAB ( X ) >= DTAB ( Y ) , ELSE 0. 

DTAB ( X ) < DTAB ( Y ) , ELSE 0. 

DTAB ( X ) <= DTAB ( Y) , ELSE 0. 



Where: 1 ACC ' is a 'DTAB* variable. 

'cc' refers to 6502 status register bits Z & C. 
• : ' is the comparison operator. 







5.4 Graphics package 

This package contains the routines listed below, all having 
functions related to generating memory map graphics using the 
system Display handler (S : ) . 



GMOVE 

INTEST 

MOD 360 

S ETC UR 

SINVAL 

TMULT 

TADDI 

QMULT 

QDIV 

QNEGA 



Plot point or draw/fill line (v/ith screen clipping). 
Test x,y point for being inside the screen limits. 
THETA = THETA modulo 360. 

Convert coordinate systems and set system cursor. 
Calculate SINE (THETA). 

Triple precision signed multiply. 

Triple precision signed addition. 

Quadruple precision signed multiply. 

Quadruple precision signed divide. 

Quadruple precision negate. 



Other routines exist in this package, but they are oriented 
directly to the syntax of PILOT graphics sub-commands; 
specifically, there are routines to process the following 
sub-commands : 



DRAWTO x , y 
DRAW n 
GOTO x,y 
GO n 

FILLTC x , y 
FILL n 
TURNTO 0 
TURN 0 
CLEAR 
PEN c 
QUIT 



The most interesting of the routines is GMOVE which contains a 
screen clipping algorithm which allows lines to be drawn 
anywhere within a 65535 by 65535 graphics address space, 
displaying the line segments which pass through the 160 by 96 
visible screen. The algorithm implemented is described in 
section 5-1 of PRINCIPLES OF INTERACTIVE COMPUTER GRAPHICS, 
Second Edition. 
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5 . 5 Statement 






scanning utilities 



The statement scanning utilites aid in 
statements. In general, most of these 
character in the A register or expect 
into the line pointed to by INLN. The 
primary utilities and summarizes their 



the scanning of PILOT 
routines expect a single 
the Y register to index 
table below lists the 
calling sequences . 



Name Function 



CNUM3R 

CLETTR 

CKECA 

CHKEQS 

CHKSEP 

CHKTPsM 



Check A = numeric character. 

Clear carry if A = *0* - '9*. 

Check A = alphabetic character. 

Clear carry if A = 'A' - ' 2 ' . 

Check A = end of atom (non-alphanumer i c character). 
Set cc non-zero if A = 1 $ • - 1 9 * or 'A'- - *2*. 

Check A = equal sign. 

Set cc zero if A = ’ = ' . 

Check A = comma or soace . 

Set cc zero if A = • , * or 1 * . 

Check A = statement terminator. 

Set cc zero if A = <EOL> or 1 [’. 



SCNEOA 

SCNLBL 



SL3 

SKPSEP 

SCNECL 



Scan to end of atom (non-al phanumer ic character). 

Y = index for pointer INLN. 

Scan to end of label, if present. 

Y = index for pointer INLN. 

Skip over leading blanks. 

Y = index for oointer INLN. 

.t* 

Skip over separators. 

Y = index for pointer INLN. 

Scan to end of line. 

Y = index for pointer INLN. 
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